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CGI and data security 



by Paul A. Watters 

The CGI (Common Gateway 
Interface) is a popular meth- 
od of operating on user data 
collected from an HTML <FORM> 
on a Web site. We can use CGI to 
process data by either an interpret- 
ed Perl or shell script, or a com- 
piled program, which resides on 
the server. We can then return 
either a dynamically generated 
HTML page, or some other kind of 
data (for example, a graphics file) 
from the server-side application. 
However, the increased use of CGI 
programs has given rise to a num- 
ber of recent security concerns, 



which potential users of custom- 
made applications and off-the-shelf 
scripts should be aware of. 

CGI: Compiled or 
interpreted? 

Applications that make use of the 
CGI interface have become increas- 
ingly popular on Solaris-based 
server systems, with which person- 
al computers of many descriptions 
can interface using the WWW. A 
common example is a Web inter- 
face to a centralized database sys- 
tem. As shown in Figure A, a client 
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using a low-end PC can execute complex 
searches on a remote Solaris machine, 
accessed by HTML forms utilizing the CGI 
interface, without increasing overheads on 
their local machine. The results of the search, 
which might include graphics, text, and 
sounds, can then be returned in a dynamically 
generated Web page. This approach strongly 
supports the client-server model in a Web 
environment, providing access to up-to-date 
information at call. 

CGI appeals to two main audiences: novice 
users and experienced users. Novice users 
often use freeware scripts downloaded from a 
resource site to include many advanced ele- 
ments on their Web pages (like page counters, 
time/ date displays, and guestbooks), without 
having to learn how to program. 

Alternatively, experienced users, based in 
medium-to-large businesses, often use CGI to 
provide a modern interface to legacy systems, 
which might be expensive to rewrite in a 
modern compiled language (like C++). This 
approach not only saves money on expensive 
reprogramming, which must often be per- 
formed from the ground up, but enables a 
very fast turnaround time on providing a 
modern Web-based interface for clients. 

There are certainly more general uses of 
CGI than we'll be looking at in this article. 
However, as we'll see, casual users are vulner- 
able to CGI exploits because they're not aware 
of some features of UNIX shell scripts, while 
experienced programmers might not be aware 
of the many exploits that are currently avail- 
able over the Internet. 

Query strings: Size matters 

Currently, the major concern in Web security 
is the power of CGI scripts to unwittingly 
facilitate the execution of rogue programs on 
a server through a query string passed from a 
client. Mistakes in writing CGI scripts can 
allow malicious users to gain access to key 
system accounts. It's very important to learn 
the first law of CGI programming: parse 
everything! Every query string must be treat- 
ed as if it were being executed on the com- 
mand line, as that's the level of access which 
some exploits can provide for intruders. 
Planning for the worst-case scenario also 
ensures that less-serious exploits can be suc- 
cessfully dealt with. 

The major concern with the content of 
query strings is that they can contain non- 



alphabetical characters like the tilde (~), 
which often have a special meaning in UNIX, 
and can be used in some cases to execute 
malicious commands. An example is using the 
eva I statement from the Bourne shell and Perl 
scripting language, which will quite happily 
evaluate a query string with a semi-colon 
appearing somewhere within it. The semi- 
colon will, no doubt, be followed by a mali- 
cious command to mail the entire system's 
password file to a waiting hacker (although 
password shadowing can reduce the risk of 
non-root access to the password file). Using 
an additional code segment in shell scripts or 
Perl can usually fix this kind of problem — for 
example, all input can be parsed by a function 
to remove all non-alphabetical characters. 

It isn't only the content of query string that 
we have to be conscious of; as with many 
things in life, size also counts. One problem 
with passing a query string is that the authors 
of some off-the-shelf scripts and compiled 
programs don't check the length of the query 
string, and usually declare the variable that 
stores the query string to be of constant size. 
For example 

char query_stri ng[ 1024] 

allocates 1024 bytes to the variable query_string 
of type char, assuming that 1024 bytes will be 
the maximum argument size passed. We can 
see the folly of declaring variables in this way 
when there are a number of well-known 
exploits available on the Web that pass extra- 
neous bytes after the declared 1024 to over- 
write the address space declared for the 
query_string variable. This allows malicious 
users to execute arbitrary commands on the 
server in some cases. 

The count.cgi program, for example, which 
is used to record and display the number of 
times a WWW page has been accessed, is a 
script widely used by non-programmers. 
However, failing to declare array sizes 
dynamically potentially allows the stack space 
of the program to be overwritten when a spe- 
cific set of arguments is passed in the query 
string (CERT Advisory AA-97.27). Intruders 
can force the count.cgi program to execute 
arbitrary commands with the privileges of the 
server daemon. If the daemon is run as root 
(that is, where all child processes have root 
privileges), the results could be disastrous for 
the entire system, not just the Web interface or 
files in the document root directory. If you're 



still running an old version of this program, 
CERT advises you to update immediately: 

www.fccc.edu/users/muquit/Count.html 



if (CONTENTJ.ENGTH > 1024) then 
reject_query( ); 

might be a useful remedy, if we have a stan- 
dard error message defined in re j ect_query ( ). 

System solutions 

Other CGI security solutions are aimed at the 
system level. For example, CGI.pm is a Perl 
library that parses and interprets strings com- 



posed of HTML queries in a standard, secure 
way. Using a standard programming library 
can save mistakes and simple errors that 
might not result in any observed changes in 
an application's behavior, but might open 
potential security holes. More information 
about CGI.pm can be found at: 

stein.cshl.org/WWW/software/CGI/ 
cgi_docs.html 

Of course, the best solution in the lone run 
might be to install a safer Web server — one 
that incorporates many existing CGI-related 
security strategies in its code. The apache 
Web server, for example, now has the suEXEC 
feature, which is designed to screen all CGI 
requests using a wrapper before any user- 
level scripts or programs are executed. 
SuEXEC also allows users to run CGI scripts 
and programs under usernames that are dif- 
ferent from the standard nobody or www under 
which the daemon usually runs (or worse 
still, allowing child processes of the server 
daemon to run as root). 

This feature considerably reduces the 
many security risks involved with allowing 
non-system users to run CGI programs for 
public use (using a wrapper is really manda- 
tory on multi-user systems like Solaris). 
SuEXEC also refuses to run programs that 
don't meet a certain number of security-based 
criteria; for example, if extra arguments are 
passed, or if the directory with the CGI pro- 
gram is writeable by other users, then the 
query request is rejected. For servers where a 
high level of security is required, it's better 
not to run the server as root at all (for exam- 
ple, starting the daemon by a user like nobody 
on a high-numbered port). Even compiled 
code can potentially be exploited if the source 
code is freely available over the Internet — 
potential loopholes or coding errors might be 
exploited by an enthusiastic competitor or a 
bored hacker. This might seem like overkill, 
but when our businesses rely on providing 
reliable, Web-based information services, 
such precautions are mandatory. 

Further reading 

The definitive guide to CGI security can be 
found at: 

www.w3.org/Security/Faq/ 
www-security-faq.html 



Code solutions 

The first technique that can be used to stop 
malicious use of a query of a large size is to 
dynamically allocate memory, depending on 
the size of the query string, which can fortu- 
nately be determined from an environment 
variable. Thus, if the size of the query string is 
passed by the variable CONTENT_LENGTH, we can 
simply declare a pointer to an array of type 
char (in C), and then set its size dynamically 
in the program, after CONTENT_LENGTH has been 
read from the environment: 

query_s t r i ng=( char *) calloc((size_t) 
CONTENTJ.ENGTH, sizeof(char)); 

This means that the bounds of the array 
query_s t ri ng can't be overwritten. 

However, although this technique will stop a 
user from executing arbitrary commands on the 
server, it isn't enough to stop denial of service 
attacks that might be aimed at crashing the serv- 
er and preventing access from paying clients, for 
example, rather than stealing passwords. In this 
case, several megabytes of data might be passed 
as a query string, eventually consuming all 
available physical memory and swap space. 
Even if enough memory is available to process a 
single query, the performance of the server will 
be dramatically reduced during processing. If 
two or three clients repeated this query consecu- 
tively, there's real scope for almost permanently 
denying service. One way of avoiding this kind 
of problem is to place a sensible limit on query 
strings, by rejecting input streams that are larger 
than the maximum required for any particular 
page on the server. A 1024-byte limit is generally 
sufficient for most Web pages, although it might 
need to be larger for complex query strings. For 
example, a simple check such as 
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The best guide for general security issues for 
Solaris systems can be found at: 

www.sunworld.com/common/ 
security-faq.html 

This FAQ contains a section "How do I make 
my Solaris Web server more secure?," which 



should be read by anyone considering run- 
ning a Web server under Solaris. CERT advi- 
sories can be found at: 

www.cert.org 

CERT also maintains mailing lists so that you 
can be notified of any current advisories as 
soon as they're released, 
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Shell toolbox 1 01 , part 2 



by Jeff Forsythe, Sr. 

Last month, in part 1 of this article, you'll 
recall that we were building an editing 
library and we gave you the lognsg func- 
tion and the header function to chew on. Hope- 
fully you've put them to use already. This 
month, in part 2 of the article, we'll finish the 
library. So, let's dive right in. 



Shell scripts 



Our plan will add shell.sh, shown in Listing A, 
and file.sh to your toolbox next. They're similar 
in nature, but have a few differences. We'll 
demonstrate shell.sh and leave file.sh to you. 
Then, you'll build your edit.shlib because you 
can finally get some functionality out of the 
previous tools as a unit. You'll want to build 
vc.sh, shown in Listing B on page 6, quickly 
because it's the Easter Egg of the entire library. 
And finally, if you're so inclined, you'll want to 
build the affects.sh program (remember that 
this is vaporware for the author who would 
appreciate if you could email a copy of your 
affects.sh if you build one). Now that we have 
the plan down, let's get to work. 

shell.sh 

The next tool is the shell.sh program. It still 
could use some work, but has been so handy 
for six years and is such an integral part of the 
edit.shlib that it must be presented as-is. 

The shell starts by obtaining all the perti- 
nent information required to create the docu- 
ment header: Name, Author, Purpose, etc. 
Don't forget to change the AUTHOR= lines to 
default to your initials. The shell then creates 
a header and sends you to vc.sh. This pro- 



gram, like most of the others, is a simple, 
easy-to-follow utility. With minor modifica- 
tions, it will work by itself. In fact, if you look 
closely at the weird way vc.sh is called, you'll 
probably guess that it was an after-thought (of 
about six years). 

For your sake, spend the time to type in 
vc.sh rather than editing shell.sh to work by 
itself; it's worth it. Finally, you'll notice that 
the header contains starting and ending lines 
of 57 pound signs (#). This, you'll recall from 
last month, is used by header.fnc and must be 
exactly 57 in order to work. Now you can put 
shell.sh to work for the first time. 

Creating internal 
documentation 

For those of you who enjoy documenting after 
a program is written, or who wish to docu- 
ment your previously developed scripts, you 
can move the original shell to a temporary 
name, run shell.sh with the correct name, and 
then read in the temporary name you just cre- 
ated. This will create the internal documenta- 
tion and get you where you need to be. Huh? 
To demonstrate, you should use this method 
to update logmsg.fnc and header.fnc (both 
were presented in part 1 of the December 1998 
issue) to add the proper header documenta- 
tion to them. 

First, move logmsg.fnc to logmsg.nd (nd 
for no docs). Then, run shell.sh, logmsg.fnc, 
and answer the prompts. When you're ready 
to edit, just read in the logmsg.nd file (in vi, 
you type colon (:), the letter r for read, and 
the file name :r logmsg.nd). When you save 
and exit, you'll be saving logmsg.fnc with 




Listing A: shell.sh listing 



J 



#!/bin/sh 



SHELL: 

DATE WRITTEN: 
DATE UPDATED: 



PURPOSE: 

# USAGE: 

# FLAGS: 

# ARGUMENTS: 

# RETURNS: 
# 

# 

# CALLS: 
# 

# 

# CALLED-BY: 

# ERRATA: 

# LIMITATIONS: 
# 



shell.sh 

08/24/92 JAF, Sr. 
09/18/98 JAF, Sr. v4.01 
Fixed typo 

Used to create shell scripts 
shell.sh shell-name! .sh] 
None 

she I L-name 
0 - Nominal 

1 - Invalid number of arguments 

2 - Attempting to create a 
file that exists 

${FNCDIR}/logmsg.fnc 

$(SHELLDIR}/vc.sh 

${SHELLDIR}/header.sh 
N/A 
None 
None 



. ${FNCDIR}/logmsg.fnc 

logmsg shell.sh S Started ${LOGDIR}/shell. log 

if [ $# -ne 1 ] 
then 

echo "USAGE: shell.sh shel l-name[ . sh ]" 
logmsg shell.sh E "Invalid number of 

arguments $#" ${LOGDIR}/shel I . log 
logmsg shell.sh F Finished ${ LOGDIR} 
/shel I . log 

exi t 1 

fi 

VERNAME="${1}" 

if [ -s ${VERNAME} ] 
then 

echo "$f VERNAME} exists, use: vc.sh 
*{ VERNAME } - exiting" 

exit 2 

fi 

if [ "echo ${ VERNAME} I grep -c .sh' -eg 0 ] 
then 

VERNAME= "${ VERNAME } . s h " 

f i 

SHELLNAME=${ VERNAME }$$ 



echo "Purpose: \c" 
read PURPOSE 

AUTHOR=" Inside Solaris Reader" 

echo "Author's Initials [${AUTHOR}]: \c" 

read AUTHOR 

if [ "${AUTHOR}" = "" ] 
then 

AUTHOR=" Inside Solaris Reader" 

fi 



» ${ SHELLNAME } 



echo "#!/bin/sh" 
echo 

» ${ SHELLNAME} 
echo "#" » ${ SHELLNAME} 
echo "# SHELL: ${VERNAME}" » 

${ SHELLNAME} 
echo "# DATE WRITTEN: 'date +%mAdAY' 

$f AUTHOR}" » $( SHELLNAME} 
echo "# DATE UPDATED:" » ${ SHELLNAME} 
echo "# PURPOSE: ${PURPOSE}" » 

${ SHELLNAME} 
echo "# USAGE: 

${ SHELLNAME} 
echo "# FLAGS: 
echo "# ARGUMENTS: 
echo "# RETURNS: 

${ SHELLNAME} 
echo "# 



${ VERNAME}" » 

None" » ${ SHELLNAME} 
None" » ${ SHELLNAME} 
0 - Nominal" » 

1 Ji 



echo 
echo 
echo 
echo 
echo 
echo 

echo 
echo 



Invalid number of arguments" » ${ SHELLNAME} 



'# CALLS: 
'# CALLED-BY: 
'# ERRATA: 
'# LIMITATIONS: 



N/A" 
N/A" 

None" 
None" 



'#" » ${ SHELLNAME} 

» ${ SHELLNAME} 
" " » ${ SHELLNAME} 
" " » ${ SHELLNAME} 



${ SHELLNAME} 
${ SHELLNAME} 
> ${ SHELLNAME} 
■ ${ SHELLNAME } 



logmsg shell.sh M "vc.sh -tmp ${ SHELLNAME} 
${VERNAME}" ${LOGDIR}/shell.log 

vc.sh -tmp ${ SHELLNAME} ${ VERNAME} 

chmod + x ${ VERNAME} 

rm -f ${ SHELLNAME } 

logmsg shell.sh F Finished ${ LOGDIR }/s he 1 1 . log 
exit 0 



documentation. Now do the same thing with 
header.fnc. When you're done, you can 
remove the *.nd files (but make sure you 
don't have anything with this ending prior to 
this exercise). 

The file.sh program is nothing short of a 
modified shell.sh. In order to create it, you 
run the shell.sh command with file.sh as the 



argument. Then, after answering the header 
prompts, you read in shell.sh and modify the 
header and the header that it creates. The 
purpose of file.sh is to do the same thing for 
non-shell script text files as shell.sh does for 
scripts — namely, to create a documentation 
header. In the interest of column space, this 
is left as an exercise for you. 
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Listing B: vc.sh Listing 



#! /bin/sh 
# 

# SHELL: 

# DATE WRITTEN: 

# DATE UPDATED: 
# 

# PURPOSE: 
# 
# 
# 

# USAGE: 

# FLAGS: 

# ARGUMENTS: 

# RETURNS: 
# 
# 

# CALLS: 
# 
# 

# CALLED-BY: 

# ERRATA: 

# LIMITATIONS: 
# 



vc.sh 

03/02/1998 JAF, Sr./rlh 
04/10/1998 JAF, Sr. v2.01 
Added -tmp flag 

Implement file version numbering. 
Taken from "Sys Admin" Vol. 3, 
No. 5. 

Sept/Ocf 1994 and HIGHLY MODIFIED! 
vc.sh [-tmp file] file [file...] 
-tmp file: temporary file 

f i le [f i le . . . ] 

0 - Nominal 

1 - Invalid number of arguments 

2 - Fi le sums do not match 

3 - Error creating backup of 
original file 

/usr/bin/vi 
*{FNCDIR}/logmsg.fnc 
SfUTILDIRJ/mode.sh 
N/A 

None 

None 



. ${FNCDIR}/logmsg.fnc 

# Check to ensure that at least one input 

# option was entered, 
if [ $# -It 1 ] 

then 

vc.sh [-tmp file] file 

.]" 



"-tmp" ] 



-It 3 ] 



echo "Usage: 
[file .. 
exi t 1 
else 

if [ = 
then 

if [ $# 
then 

echo "Usage: vc.sh [-tmp file] file 

[file...]" 
exit 1 

fi 

USETMP="TRUE" 
TMPFILE=S2 
shift 
shift 
else 

USETMP="FALSE" 

fi 

f i 

# Check for ${HOME}/.vc.cfg 
if [ -s ${HOME}/.vc.cfg ] 
then 

MAXVER=~grep MAXVER ${H0ME}/ . vc . cf g ! 

awk '{print $2}" 
VERDIR=~grep VERDIR *{ HOME } / . vc . c f g ! 

awk '{print $2}" 

else 

MAXVER=${MAXVER:5} 



VERDIR=${ VERDIR : . } 



LOG=S{VERDIR}/vc. log 

# loop for each file in the argument list 

for FILE in $« 

do 

# Set DIR 

DIR='dirname ${ FILE}' 

# Set FILE 

FILE='basename ${FILE}' 

# Set flag for ownership, group and mode 
M0DEFLAG=FALSE 

# Get the last version present 
LASTVER="Ms ${ VERDI R } /${ F I LE } \ ; . 

2>/dev/null ! sed 's/.*;//g' ! 
sort -rn I head -V" 

if [ "${ LASTVER}" != "" ] 
then 

# Check sum on original and highest 

# version 

if [ '"sum -r ${DIR}/i{FILE} ! awk 
'{ print $1 )'-' != \ 

'"sum -r ${VERDIR}/${FILE}\; 
t{ LASTVER J ! awk '{ print $1 }•'" ] 

then 

banner "ERROR" 

echo "\n\n Highest version 

and original f i le" 
echo "do not match. This 

could be a f i le out" 
echo "of sync or they 

could be two different" 
echo "f i les from different 

di rectori es . " 
exit 2 

fi 

# Increment the version number. 
VER='expr ${ LASTVER} ♦ V 

if [ ${VER} -gt i{ MAXVER} ] 

# Do not exceed MAXVER copies, 
then 

cp ${VERDIR}/${FILE}\;1 
${VERDIR}/${FILE}\;tmp 

# Start with 2 so that 2 replaces 1, 

# 3 replaces 2, etc. 
C0UNT=2 

while [ ${ COUNT} -le ${ LASTVER} ] 
do 

LESSONE=~expr ${COUNT} - V 

mv *{VERDIR}/${FILE}\;${COUNT} 
${VERDIR}/${FILE}\;${LESSONE} 



done 



COUNT='expr t{COUNT} * V 
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Listing B: continued 



VER=${MAXVER} 

LASTVER='expr ${LASTVER} - V 

fi 

ORIG="${VERDIR}/${FILE};${LASTVER}" 
NEWFILE="${VERDIR}/${FILE};${VER}" 

MODE= s Is -I ${DIR}/${FILE} ! 

awk '{print $1 }" 
OWN='ls -I ${DIR )/${FILE} ! 

awk '{print $3}" 
GRP="ls -I ${DIR}/${FILE} ! 

awk '{print S4}" 
MODEFLAG=TRUE 
else 

# Thi s i s a new f i le - start the 
#version at 1. 

VER=1 

ORIG="${DIR}/${FILE}" 
NEWFILE="${VERDIR}/${FILE};${VER}" 

# Check to see if the fite REALLY 
#EXISTS. 

if [ ! -f ${0RIG} ] 
then 

touch SfORIG} 
else 

cp *{0RIG} *{VERDIR}/${ORIG}\;0 

fi 

fi 

# Copy the last edit file to the new 

# version for editing. 

if [ "${USETMP}" = "TRUE" ] 
then 

ERR=~cp ${ TMPFI LE } ${ NEWFILE} 2>&1; 
echo $?' 

else 

ERR='cp ${ORIG} ${ NEWFILE} 2>&1 ; 
echo $?' 

fi 

# Check for copy error, 
if [ ${ ERR } -ne 0 ] 
then 

ERR="echo $ERR ! sed 'si.*: //g' 2>&T 
echo "Your edit of ${NEWFILE} is aborted." 
echo "Attempting to access ${ORIG} 

has reported the following \c" 
echo "system error:\n\n\t${ERR}\n" 
echo "Aborting edit." 
exi t 3 

fi 

echo "Loading ${ NEWFI LE } for edit ..." 

# Load vi and edit f i le 
/usr/bin/vi + ${ NEWFILE} 

if [ ${VER} -gt 1 ] 
then 

# Check to see if user actually 

# made changes . 

diff *{ORIG} ${ NEWFILE} 2>&1 >/dev/null 
EDIT=$? 



else 

# This is the first edit - so don't run 

# diff command 

if [ -r ${ NEWFI LE } ] 
then 
EDIT=1 

fi 



if [ ${ EDIT } -eg 1 ] # The user DID make 

# changes 
then 

# Remove the pre-edit file and the 

# tmp copy. 

rm -f ${DIR}/${FILE} ${VERDIR}/ 
${FILE}\; tmp 

# Copy the newest file to the basename. 
cp ${ NEWFILE} ${DIR}/${ FILE} 

if [ "${MODEFLAG}" = "TRUE" ] 
then 

NEWMODE='${UTILDIR}/mode.sh ${MODE}~ 
chmod ${NEWMODE} « { DIR } /*{ FILE } 
chown t{0WN} ${DIR}/${ FILE} 
chgrp ${GRP} S{ DI R }/${ FI LE } 

fi 

logmsg $0 M "${L0GNAME} changed 
${DIR}/${FILE}" ${LOG} 

else 

logmsg $0 M "${ NEWFI LE } was not edited. 
Restoring to ${0RIG}" ${LOG} 

# Remove the higher version because 

# NO changes were made, 
rm ${ NEWFI LE } 

# Move files back to original names, 
if [ -s ${VERDIR}/S{FILE}\;tmp ] 
then 

# MAXVER -1, so that we can 

# move the f i les back up unti I 

# 1 becomes 2 

# and then we move the temp file 

# in as 1 . 

COUNT='expr ${MAXVER} Ji V 
while [ ${COUNT} -ge 1 ] 
do 

PLUSONE=~expr ${COUNT} + V 

mv ${VERDIR}/${FILE}\;${COUNT} 
*{ VERDIR }/${ FILE }\ ; ${ PLUSONE } 

COUNT=~expr ${COUNT} - r 
done 

mv S{ VERDIR}/*{FILE}\; tmp 
${VERDIR}/${FILE}\;1 

f i 

f i 
done 

exit 0 
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Version control 

That brings us to version control. How many 
times have you made changes to a script only 
to find out a day or two later that your 
changes don't work and you want to roll back 
to the previous version? With vc.sh in place 
and used properly, you'll have this option at 
your fingertips. 

The version control script, vc.sh, first 
checks to see if there's a previous version con- 
trol file. If there isn't, the file is copied to a 
backup and given a semicolon zero extension 
(filename;0). If the version control file does 
exist, a copy is made to the next higher num- 
ber. The only exception to this rule is when 
the numbers exceed the maximum number of 
version control files. The maximum is set to 
five by default and can be controlled through 
an environment variable (MAXVER) or through 
the configuration file vc.cfg (which was creat- 
ed with file.sh). 

If it exists, vc.cfg is kept in the user's home 
directory and is specific to that user. If the 
maximum number is reached, the lowest 
number (filename;!.) is moved to a temporary 
name and each subsequent higher number is 
moved down to the next lower number (for 
example, filename;2 becomes filename;!.). 
After the version control routine is completed, 
the editor is called. 

Should the user exit without making any 
changes, the files are all reset to their original 
positions prior to vc.sh being called. That's 
why we keep filename;l in a temporary loca- 
tion. If changes were made, then the temporary 
copy of filename;l gets removed (if it exists). 

Storing backup files 

There are several schools of thought about 
how to store the backup files. We'll describe 
each thought, but for this article, we'll imple- 
ment the third school of thought — storing the 
backup files in the same directory. 

Backup directory 

One school of thought says to keep the back- 
up files in a special directory set up just for 
backup files, thus making them easier to back 
up separately from the nightly backup (the 
author's personal favorite — but slightly more 
difficult to implement). 

The biggest drawback to this idea is that if 
you have files in multiple locations with the 
same name, they'd get mixed up with one 
another in the backup directory. However, 



vc.sh is aware of this possibility and performs 
a checksum on the latest file (highest number) 
and the file being edited. If they don't match, 
the user is warned that there's a problem. This 
method is also implemented as a means of 
checking for someone editing the file without 
the use of vc.sh. 

Another problem with this method is that 
the backup directory's write permissions need 
to be opened up for everyone. This, obviously, 
isn't a good idea. 

Separate file system 

Another school says to create a separate file 
system that mimics the original under the 
mount point /vc. This option is an offshoot of 
the first in that it creates a mimic file system. 
For instance, if you were going to edit 
/ etc/hosts, the backup file would be stored in 
/vc/etc/hosts;l. It doesn't take long to see the 
drawbacks in this idea. 

First, the file system must get copied to the 
backup area. This takes up overhead unneces- 
sarily and takes up a disk slice for the file sys- 
tem. The script is written using the VERDIR 
variable, which can be set in the .vc.cfg con- 
figuration file. This variable determines the 
location of the backup files. 

Same directory 

The final school says to keep the backup files 
in the same directory as the original. That's 
the easiest to implement and the one we'll 
show in this article. 

If you want to perform a separate backup 
of the version control files, you search for files 
that end in a semicolon and a number. It's 
also nice to look only in /etc for hosts* rather 
than looking in / etc and one or more other 
locations for backups. This particular shell is 
an Easter Egg in disguise. Once you have it 
implemented, you'll know within a day or so 
why it's so useful. 

Moving back to an older version after an 
editing session is as easy as remove and copy. 
Remove the highest numbered version and 
copy the next higher version to the edit name. 
If you don't like edit number 5 of the 
/ etc /hosts file, remove number 5 and copy 
number 4 to /etc/hosts. 

A very important point about vc.sh is that it 
uses the semicolon in the filename. The semi- 
colon is a special character because it's also a 
statement separator in Solaris. So it's important 
to escape the semicolon when using it. That is 
to say, when you want to copy or remove a file 



with the semicolon, you need to use a backslash 
(\) prior to the semicolon. For example, rm 
/etc/hosts\;5 and cp /etc/hosts\;4 /etc/hosts. 
If you leave the backslash out of the rm state- 
ment (rm /etc/hosts;5), Solaris will try to 
remove /etc/hosts and then execute a program 
called 5. The cp statement would give an error 
because you're trying to copy /etc/hosts to 
nothing and then execute a program called 4 
with a command line argument of /etc/hosts. 
Be careful when using the semicolon in file- 
names! We could use some other character, but 
the semicolon looks nice in an Is output. 

Holding it all together 

Last month, we promised you some string 
and rubber bands to hold this all together. The 
vc.sh uses a configuration file (the string) and 
calls another script called mode.sh (the rubber 
band) shown in Listing C. Listing D, on page 
10, shows an example vc.cfg configuration 
file — which was created using file.sh. You can 
change the settings for each user and place 
this in their home directory. The VERDIR is 
the setting you can use to save the files in a 
location other than the current directory, as 
previously stated. Just give the full path to the 
verdir of your choice such as ${HOME}/verdir. 

The vc . sh script also calls a program called 
mode . sh, which isn't included in the library but 
is necessary for vc.sh to work. It accepts the 

Listing C: mode.sh Listing 



string mode of a file and returns the numeric 
mode. You can see the example in the header. 
This utility doesn't accept all string modes, 
but it works on almost every file. 

Send your updates to the author. This 
script might well become a function after you 
see it's utility. Many programs can use mode . sh 
to set the mode of a file. 

affects.sh 

We discussed the vaporware affects.sh earlier. 
The idea is simple, but implementation is a 
challenge. If you're a weak-in-the-knees shell 
script programmer, read no further, skip to 
the next article. The affects.sh program uses 
the header function from header.fnc to find 
the CALLS and CALLED BY sections, and 
then attempts to determine if the changes you 
made to the current script have any affect on 
the scripts (if any) in these sections. If so, 
affects.sh notifies and asks if you want to edit 
the affected files. You could conceivably use 
this to test program source code as well if the 
location of the code is given. 

You're a hard-core programmer if you 
implement this concept. Of course, this is a 
recursive procedure because editing changes 
made to the affected script may affect others. 
Therefore, affects.sh must trace the CALLED BY 
linage first and then the CALLS section next. As 
you can see, this can get really deep, fast. 



#!/bin/sh 



# 








# for them. 


This 






SHELL: 


mode . sh 




# works out 


well when 


# 


DATE WRITTEN: 


03/23/1998 


JAF, Sr. 


case $1 in 






# 


DATE UPDATED: 






■■__.") 


NUM=0 




# 


PURPOSE: 


Translate string mode into 


"-X") 


NUM=1 




it 




numeric 




"-W-") 


NUM=2 




U 


USAGE: 


mode. sh 




"-WX") 


NUM=3 




# 


FLAGS: 


None 




"r-") 


NUM=4 




# 


ARGUMENTS: 


String mode 


ex. drwxrwxrwx. 


"r-x") 


NUM=5 




# 




-rwsr-xr-x) 




"rw-" ) 


NUM=6 




# 


RETURNS: 


Numeric mode 


(ex. 777, 4755) 


"rwx" ) 


NUM=7 




# 


CALLS: 


N/A 




"-S") 


NUM=1 1 ; ; 




CALLED-BY: 


N/A 




"-ws" ) 


NUM=13; ; 


# 


ERRATA: 


None 




"r-s" ) 


NUM=15; ; 




LIMITATIONS: 


Doesn't hand 


e all modes 


"rws") 


NUM=17;; 


# 








esac 







############################### #### # ########################## 



get_num( 



{ 



# Other modes can be added to the case 

# statement as needed 

# setuid bits are set to 11-17 



# because we couldn't use 1-7 



M0DE=$1 

USER='echo ${M0DE} 
getjium ${USER} 
if [ ${NUM} -gt 7 



cut -c2-4~ 
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Listing C: continued 



then 



OUT=~expr 3000 + ${NUM} \. 100~ 



0UT='expr ${NUM} \. 100' 

f i 

GR0UP=~echo ${M0DE} ! cut -c5-7' 
getjium ${GR0UP} 
if [ ${NUM} -gt 7 ] 
then 



0UT="expr ${0UT } + 1900 + ${NUM} \* 10' 



else 



OUTVexpr ${0UT} ♦ ${NUM} \» 10 % 



fi 



OTHER='echo ${M0DE} ! cut -c8-10' 
get_num S{ OTHER} 
0UT=~expr $(0UT} + ${NUMK 

echo ${0UT } 



Listing Dl Example .vc.cfg configuration file 



# .vc.cfg 

# configuration f i le for 
MAXVER 5 

VERDIR . 



vc.sh for Inside Solaris Reader 



The hardest part will be determining if a 
change made to the current script has any 
affect on others. This can be accomplished by 
checking for an environment variable or file 
changes that are in both scripts, and by 
checking for differences in the flags or com- 
mand line arguments of the scripts. Do you 
think that's all it will take? But isn't that 
enough to make you feel tingly all over? 
Version 1.0 should just list the files in the 



CALLS and CALLED BY sections and ask if 
the user wishes to edit them. Perhaps it will 
store them in a temporary file for later use. 
Then Version 2.0 will go full-blown. Feel free 
to code this script and email it to the author. 
Or, send it to Inside Solaris, as an article for an 
upcoming issue. 

Summary 

The edit.shlib is now complete, well almost. 
In Solaris, as in all UNIX development, every- 
thing is a work in-progress. As for the library, 
you now have many tools at your fingertips 
that put you miles ahead of your peers who 
don't read Inside Solaris (shameless plug). If 
you begin to use the library religiously, you'll 
see just how useful it can be. 



SOLARIS TUNING 



Improving server apps 
with scheduling under Solaris 



by Abdur Chowdhury and Andy Spitzer 

With system complexity growing each 
day, many machines are performing 
many different tasks simultaneously. 
This sharing of resources can affect the per- 
formance of your system. Understanding how 
the operating system schedules your process 
can help you architect better systems. 

Solaris is a multi-tasking pre-emptive 
operating system. The operating system is 




responsible for scheduling when each process 
runs. When a process has reached the end of 
its allotted time slice, or blocks for some rea- 
son, Solaris saves its state and runs the next 
runnable process in the process queue. This 
gives the appearance of many different pro- 
grams running simultaneously on a single 
processor. Solaris 2.6 and greater supports 
two usable process scheduling classes: real- 
time and time-sharing. 

In this article, we'll describe the concept of 
process scheduling, the major differences be- 
tween real-time and time-sharing scheduling, 
and the Solaris API to process scheduling ma- 
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nipulations. We'll also provide a simple exam 
pie of its use to improve server performance. 

- Process scheduling 

Process scheduling has one basic goal: to 
make the system more productive. To 
achieve this goal, a general-purpose operat- 
ing system must balance the following dif- 
ferent needs: 

• Allot a fair share of CPU time to each 
process. 

• Try to keep the CPU busy 100 percent of 
the time. 

• Minimize response time for time sensi- 
tive processes. 

• Minimize total job completion time. 

• Maximize total number of jobs per time 
unit. 

To achieve this balance, Solaris makes some 
assumptions about the type of processes that 
it's running. Therefore, the default scheduler 
may not always suit your application. In the 
next section, we'll present a brief background 
of several scheduling algorithms and their 
implementations . 

Solaris uses a two-level thread implemen- 
tation, where threads within a process are 
scheduled on a virtual processor known as an 
LWP (Light Weight Process). LWPs, in turn, 
are scheduled on the physical processors. 
When we talk about process scheduling below, 
we really mean LWP scheduling. Threads 
within a given process can be bound to an 
LWP, and it's the scheduling characteristics of 
the LWP that we describe below. 

Scheduling algorithms 

The research community has developed many 
optimal scheduling algorithms, but all algo- 
rithms are only optimal for certain workloads. 
There's no single solution that fits every system 
need. General-purpose operating systems face 
the problem of developing schedulers that are 
general enough to solve most needs, yet exten- 
sible enough to handle specific workloads. 

There are many different algorithms for 
choosing the next process to run. Two of the 
most common algorithms, both used by the 
Solaris scheduler, are Round Robin (RR) and 
First-In-First-Out (FIFO). 



FIFO runs each process until its comple- 
tion then loads the next process in the queue. 
FIFO can have negative effects on systems 
where processes run for an extended time. 

Round Robin allows each process at a 
given priority to run for a predetermined 
amount of time. When the process has run for 
the allotted time quantum, or if a higher pri- 
ority process becomes runnable, the scheduler 
halts it and saves its state. It's then placed at 
the end of the process queue and the next 
process is started. Note that this may be the 
most optimal solution, if the time quantum is 
longer than the average runtime of a process. 
However, context switching between different 
processes has a price: We must also consider 
the overhead (context switching time) of 
changing processes. 

With the need for different algorithms at 
different times, operating system developers 
created multilevel queue scheduling. Multi- 
level queue systems are simply several algo- 
rithms used simultaneously. Each queue is 
assigned a priority over the next queue. The 
scheduler simply starts at the highest priority 
queue, implements that queue's algorithm 
until no runnable processes remain, and then 
proceeds to the next priority queue. One queue 
could use FIFO while the other uses RR. 

Solaris implements two scheduling 
classes — time-sharing and real-time. The time- 
sharing class includes interactive processes as 
well as time-sharing processes. These two 
types of processes share the same scheduling 
table as described by the man page for 
ts_dptbl(4). Processes in the time-sharing class 
have a changing priority based on factors 
such as if they previously exceeded their 
assigned time quantum, or if they're prevent- 
ed from running for a long period of time by 
higher priority processes, or if they just sleep 
a lot. This change in priority, based on previ- 
ous behavior, is what gives Solaris wonderful 
interactive response even under heavy loads. 
Batch-type jobs with high CPU demands tend 
to have lower priority because they keep 
exceeding their quantum. Interactive type 
jobs, like Web browsers, tend to have higher 
priority because most of the time they're 
blocked (sleeping), awaiting user input. 

However, important processes, such as 
database servers or Web servers, may have 
the same characteristics as a batch job, and 
end up with a lower priority than the user 
playing Doom. To solve this dilemma, The 
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Solaris scheduler also provides a real-time 
scheduling class as of version 2.6. To provide 
soft real-time scheduling requirements, the 
scheduler must provide several services: 

• Priority Scheduling — Scheduling based 
on process class. 

• Real-Time processes won't change priori- 
ty over their lifetime — A real-time 
process will always run before a time- 
sharing process. 

• Processes must be interruptible during 
system calls and I/O operations — The 
kernel must be pre-emptable. 

Solaris provides all these services. The Solaris 
kernel is entirely pre-emptable, so process 
scheduling doesn't need to wait for a safe 
time to switch between processes. Also, when 
implementing a real-time scheduler, the situa- 
tion where a higher priority process is blocked 
waiting for a resource locked by lower priori- 
ty process, called priority inversion, can occur. 
Solaris avoids priority inversions by imple- 
menting priority inheritance protocol. A 
process that owns a resource runs at the prior- 
ity of the highest priority process that's await- 
ing that resource. This means that lower prior- 
ity processes run at a higher priority until 
they release the lock or shared resource 
requested by a higher priority process. When 
the lock is released, the higher priority 
process becomes runnable and pre-empts the 
current process. 

What does all this mean? It means the 
algorithm selected can affect the performance 
of your application, and choosing the right 
algorithm can improve your systems' per- 
formance. There are many different evaluation 
techniques such as: 

• Deterministic modeling 

• Queuing Models 

• Simulation 

• Implementation 

The evaluation of your situation with the 
above methods is beyond the scope of this 
article. Those methods of evaluation may be 
needed for some systems and Jain as a good 
source to start your evaluation [Jain 91]. 

Solaris provides two scheduling algo- 
rithms for its real-time class — RR and FIFO. 
The FIFO processes will proceed until comple- 



tion, unless they're pre-empted by a higher 
priority process or interrupted by a signal. 
Round-Robin processes will execute for a 
given time quantum if not preempted by a 
higher priority process or interrupted by a 
signal. By changing the scheduling class of 
your server applications, you can be guaran- 
teed that they will run before other applica- 
tions, thus improving responsiveness. Next, 
we'll briefly describe the API that Solaris pro- 
vides for process scheduling manipulation 
and modification. 

Process scheduling API 
under Solaris 

Solaris, as a general purpose OS, must be con- 
figurable and even modifiable. To attain this 
goal, Sun provides several utilities to view the 
default scheduling classes and change the 
process priorities and quantum. We've listed 
several of these utilities here. Our main goal is 
to provide a method of viewing or changing a 
process' scheduling parameters. All of these 
utilities use a kernel call named priocntlsys. 
Below are two such utilities: 

• dispadmin(1M ) — Displays or changes 
process scheduler parameters while the 
system is running. 

• priocnt l( 1 ) — Displays or sets scheduling 
parameters for specified process. 

System administrators that want to run a 
process at a different priority or scheduling 
class can use the -e option to pri ocnt I ( 1 ) to 
execute a command. Children that are created 
by that command will inherit the priority and 
scheduling class from the parent process. For 
example, to set your Web server process to the 
real-time class with priority 20: 

pri ocnt L -e -c RT -p 20 httpd 

Solaris also provides mechanisms to 
replace the current real-time and time-sharing 
scheduling parameters with your own. The 
use of these functions is beyond the scope of 
this article, but we included them for com- 
pleteness and for further reading. Please see 
the man pages for further information. 

• r t_d p t b I ( 4 ) — Real-time dispatcher param- 
eter table 

• t s_d p t b I ( 4 ) — Time-sharing dispatcher 
parameter table 



Developers who need to change the priority 
of their process dynamically will either use 
the priocntl function or use the POSIX real- 
time library calls like sched_setscheduler. 
Following are several such process-scheduling 
calls to control how the OS will schedule your 
process: 

• priocnt 1(2 )— Controls the scheduling of 
an active light-weight process LWP. 

• priocnt Lset( 2)— Changes the scheduling 
properties of an existing process. 

• sched_setschedu ler(3R) — Sets the schedul- 
ing policy and scheduling parameters of 
a process. 

• sched_setparam(3R) — Sets the scheduling 
parameters of a process. 

Improving responsiveness: 
Example server 

To show the usage of the API and the effects 
of scheduling on your process, we've written 
a small example. The application reschedules 
itself as a real-time process if it has root privi- 
leges; without root privileges, it will run as a 
normal time-sharing process. After reschedul- 



ing itself, the application executes a tight 
counter loop, to use cpu cycles, then the 
process sleeps for approximately 10 microsec- 
onds. When the sleep is complete, we incre- 
ment a counter. The value of the counter 
shows how many times the operation was 
accomplished. We check our counter every 
10,000 microseconds, saving the results to a 
file. We've executed four experiments: time- 
sharing with no load, time-sharing with load, 
real-time round robin with no load, and final- 
ly real-time round robin with load. To simu- 
late load on our system, we've written a pro- 
gram that loops in a tight for loop to load the 
system. See the Listings A and B, on page 14, 
for load.c and load-generator.c, respectively. 

Figure A, also on page 14, shows a chart 
with four experiments. The y-axis is the num- 
ber of operations accomplished in the allotted 
time. The x-axis is the number of the experi- 
ment; we ran 10 for each set. The time- 
sharing experiments show a degradation 
of operations from the no-load to the load 
experiments, as we'd expect. The real-time 
experiments don't show a degradation in 
performance for load or no-load. What these 
experiments do show is that real-time 



Listing A: We use load.c to schedule our processes for load testing. 



#define JEENTRENT 

ffdefine _POSIX_PTHREAD_SEMANTICS 

#1 nc L ude <sys/t imes . h> 
ffinclude <sys/ types . h> 
ffinclude <sys/socket.h> 
ffinclude <sys/stat.h> 
#i nc I ude <sys/uio.h> 



#i nc 1 ude <unistd.h> 
ffinclude <stdio.h> 
#include <fcntl.h> 
#i nc I ude <stropts.h> 
#i nc L ude <sched.h> 
ffinclude <errno.h> 

ffinclude <thread.h> 
/. 

compi le as : 

cc -g -o load load.c - 1 socket -Insl -Ithread - 1 pos i x4 

./ 

/* gloabal's «/ 
pthread_mutex_t gjnutex ; 
int g_counter ; 

struct work 
{ 

int ms ; 



1 ; 

void * worker(void *arg) 
{ 

struct work *dog = (struct work *)arg ; 
i nt x ; 

tor (;;) 
1 

/* the poll is to simulate work 

count to a 100000 then sleep for X ms «/ 
for (x=O;x<1OO000 ; x ++ ) [ ; } 
poll(0, NULL, dog->ms) ; 
thr_yield() ; 

/* lock the global counter */ 
pthread_mutex_lock(8g_mutex) ; 
g_counter++ ; 

pthread_mutex_un lock(&g_mutex) ; 

1 

return NULL ; 

1 

voi d pr i o( ) 
{ 

/* Increase our priority to Real Time Status »/ 
{ 

struct sched_param param = {0} ; 
int res ; 

param. sched_priori ty = 
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Listing A: continued 



sched_get_pri ori ty_mi n(SCHED_RR ) + 10 ; 

res = sched_setscheduler(0, SCHED_RR, Sparam) 

if (res < 0) 

{ 

fprintf(stderr, "Cannot 
sched_setscheduler(SCHED_RR), %d %s\n", 

errno, strerror(errno)) ; 
ff lush(stdout) ; 

} 

} 

1 



struct work dog 1 = {10} 
FILE *out put ; 
i n t x ; 



NULL) 



prio() ; /» Set up the priority for this process «/ 
thr_create(NULL, NULL, worker, (void .)&dog1, THR_B0UND, 



output = fopen ( "data.txt", "w+" ) ; 

for (x=0; x < 10; x++) 

1 

poll(0, NULL, 10000) ; 
pthread_mutex_lock(8g_mutex) ; 
fprintf (output, "%d\n", g_counter 
f f Lush (output); 
g_counter=0 ; 

pthread_mutex_unlock(8g_mutex) ; 

( 

fclose ( output ) ; 



Listing B: We use load-generator.c to 
create a CPU-intensive process. 

#include <stdio.h> 

int main (int argc, char **argv) 



( 



i nt x ; 

for (x=0; ; x++) 
f 

if (!x%10000O) sleep ( 1 



Figure A 
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The results of our scheduling experiments evaluation. 



scheduling can improve your applications 
performance when your system has other 
processes competing for the cpu. 

As a side note, please be careful when 
rescheduling your process to the real-time 
class. Mistakes will likely result when you 
turn off the machine and reboot it, since all 
other process will run at a lesser priority and 
will never run if your program isn't respond- 
ing. In this section, we've shown that Solaris 
has utilities and methods for controlling the 
scheduling of your processes. 

Conclusion 

Understanding your operating system's 
scheduling can help you improve your 
applications' performance. There are different 



types of scheduling algorithms, and picking 
the right one for your situation is important. 

In this article, we presented several dif- 
ferent algorithms and how they work, and 
we also presented a general overview of 
what Solaris provides to modify your 
applications scheduling. We presented an 
example program showing the benefits of 
rescheduling your process to the real-time 
class. (For additional reading see [Jain 91] 
Raj Jain, "The Art of Computer Systems 
Performance Analysis," John Wiley & Sons, 
Inc. 1991, ISBN 0-471-50336-3.) Solaris is a 
great general-purpose operating system, 
and understanding what it can do for you 
will improve the performance of your 
applications. 
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UPDATING SOLARIS 




PatchDiag Tool 



by Werner Klauser 

The PatchDiag Tool, found at 
sunsolve.sun.com/patchdiag/ 
or on Sun's patch CD-ROM, is 
a diagnostic tool that enables system 
administrators to examine a profile 
of the patches installed on their 
Solaris system against the most cur- 
rent profiles available from Sun 
Microsystems with respect to: 



• Latest revisions 

• Recommended patches 

• Security patches 

• Other patches relevant to the 
software environment 

The results of PatchDiag Tool can 
help a system administrator quickly 
determine and analyze the need for 
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applying additional patches or newer revi- 
sions of existing patches. PatchDiag pro- 
vides only patch profile information. It 
doesn't deliver or apply any patches. If a 
system administrator wants to acquire or 
apply additional patches to a system, he or 
she should use their normal Sun authorized 
service channel, or could access patches via 
the Web at sunsolve.sun.com/private-cgi/ 
patchpage.pl. 

Description 

This tool is a Perl-compiled script compati- 
ble with all systems running a Solaris 2.3 or 
later environment and with all patches 
installed in Solaris patch packet format. As 
later versions of Solaris are released, this 
tool may not be supported any longer by 
earlier versions of Solaris. 

Patches indicated as "Recommended" 
patches are the most important patches. 
They prevent the most critical system, user, 
or security-related bugs that have been 
reported and fixed to date. Patches not list- 
ed as recommended by PatchDiag should 
be used if needed. Some patches listed in 
this report can have certain platform- 
specific or application-specific dependen- 
cies and thus might not be applicable to 
your system. It's important to carefully 
review the README file of each patch to 
fully determine the compatibility of any 
patch with your system. 

Usage 

Invoke the PatchDiag Tool from a com- 
mand line. PatchDiag with no options uses 



the default variables you specified during 
system installation. It produces a summary 
status report that lists: 

• Installed patches 

• Uninstalled recommended patches 

• Uninstalled security patches patchdiag -1 
produces a more extensive audit report 
that includes all patches available perti- 
nent to software installed on the sys- 
tem. It lists: 

• Installed patches 

• Uninstalled recommended patches 

• Uninstalled security patches 

• Other related uninstalled patches 

Summary 

Using this freely available tool informs 
you of patches that Sun recommends. 
Whether the patch belongs to the recom- 
mended or security patch category, it's 
very possible that you can find the patch 
that would alleviate your problem. This 
possibility is very interesting as the year 
2000 and its potential problems approach. 
Just remember that applying pages to 
Solaris (or any operating system) can 
cause unexpected problems. Always make 
sure that your system is backed up and 
that you have a recovery plan in case you 
need to return to your pre-patch configu- 
ration. Even better, experiment on a devel- 
opment machine or a personal workstation 
before applying patches to your produc- 
tion server. ^Sv 



Coming up 

• Network routing with Solaris 

• Setting up PPP for dial-up connectivity 

• Using Solaris Jumpstart to automate your Solaris installations 



